跳转到主要内容
POST
/
api
/
v1
/
instances
部署新实例（目录驱动通过 `variantId` 或显式指定）。
curl --request POST \
  --url https://openapi.beeos.ai/api/v1/instances \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "variantId": "<string>",
  "agentFramework": "<string>",
  "providerId": "<string>",
  "providerConfig": {},
  "modelPrimary": "<string>",
  "models": [
    "<string>"
  ],
  "systemPrompt": "<string>",
  "mcpServers": {},
  "bridgeId": "<string>",
  "config": {},
  "clusterId": "<string>",
  "preferredRegion": "<string>"
}
'
{
  "success": true,
  "data": {
    "id": "<string>",
    "ownerId": "<string>",
    "agentFramework": "<string>",
    "providerId": "<string>",
    "externalId": "<string>",
    "osType": "<string>",
    "hostingType": "<string>",
    "cloudProvider": "<string>",
    "name": "<string>",
    "modelPrimary": "<string>",
    "models": [
      "<string>"
    ],
    "status": "<string>",
    "desiredStatus": "<string>",
    "endpoint": "<string>",
    "bridgeId": "<string>",
    "identityId": "<string>",
    "totalRunSeconds": 123,
    "connectivity": "<string>",
    "providerConfig": {},
    "connectivityReason": "device_disconnected",
    "haltReason": "<string>",
    "publicIp": "<string>",
    "clusterId": "<string>",
    "region": "<string>",
    "imageId": "<string>",
    "imageRef": "<string>",
    "isTrial": true,
    "expiresAt": "2023-11-07T05:31:56Z",
    "errorMessage": "<string>",
    "systemPrompt": "<string>",
    "mcpServers": {},
    "startedAt": "2023-11-07T05:31:56Z",
    "stoppedAt": "2023-11-07T05:31:56Z",
    "statusEnteredAt": "2023-11-07T05:31:56Z",
    "connectivityUpdatedAt": "2023-11-07T05:31:56Z",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "screenshotUrl": "<string>",
    "screenshotUpdatedAt": "2023-11-07T05:31:56Z"
  }
}

授权

​
Authorization
string
header
必填

通过 Authorization: Bearer <token> header 传用户 JWT 或 oag_ User API Key。两者都由 openapi-gateway 对 Auth service 验证。

JWT 与 API Key 都是 user-scoped：每个 key（以及每个 JWT） 绑定到唯一 owner，所有路由都自动放开该 owner 名下的全部资源。 跨租户访问由 handler 内的 owner-ACL 拦截 —— API 表面没有 per-route scope 词汇。

v1.1.0 已移除： 历史 scope 词汇（agents:* / tasks:* / files:* / instances:*）以及 403 insufficient_scope 错误码已下线。已签发的 oag_ key 自动获得 owner 全权限， 无需重建。之前显式传 scopes 调用 createAPIKey 的 SDK 客户端可以直接删除该参数。详见文末 changelog 迁移说明。

请求体

application/json

可以提供 目录 variantId（权威来源 —— 从 variant 抬出 agentFramework / providerId / region / scheduling hint）， 或者显式给 agentFramework（+ 可选 providerId）。 客户端提供的调度字段（ownershipPreference / maxPricePerHour / resourceTypeHint）不在此处接受；目录 variant 是唯一来源。

​
name
string
必填
Maximum string length: 128
​
variantId
string
Maximum string length: 128
​
agentFramework
string
Maximum string length: 64
​
providerId
string
Maximum string length: 64
​
providerConfig
object

自由格式的 Provider 特定配置，与目录配置合并（key 冲突时 目录优先）。

​
modelPrimary
string
Maximum string length: 128
​
models
string[]
Maximum string length: 128
​
systemPrompt
string
Maximum string length: 8192
​
mcpServers
object
​
bridgeId
string
Maximum string length: 128
​
config
object

providerConfig 的替代名；语义相同。variant 驱动路径用 它把用户额外项（apiKeys / apiBaseUrls）叠在目录配置上。

​
clusterId
string
Maximum string length: 128
​
preferredRegion
string
Maximum string length: 64

响应

标准信封；data 为创建的实例。

​
success
boolean
必填
​
data
object
必填